Asset Integration Overview
Introduction
The Assetic Asset REST API's allow an asset to be retrieved, created, and updated.
Asset Register Structure
There are some important concepts to understand before the API's can be fully utilised.
Background reading in the Asset Registers article may also assist in understanding the asset data structure.
- Assets - The primary definition of the asset. Relevant API's are in the path /api/v2/assets and are referred to as the Asset API's within this article
- Components - An asset may have 0,1 or many components. Relevant API's are in the path /api/v2/components and are referred to as the Component API's within this article
- Network Measures (dimensions) - Each component may have 0,1 or many network measures.
- Functional Location - Allows assets to be grouped together for reporting and navigation. An asset can belong to 1 functional location only. Functional locations can be nested up to 6 levels.
- Refer to the Assetic Knowledge Base article Asset association with Functional Location for associating an asset to Functional Location.
- Asset to Asset Association - allows assets that have a relationship to be associated with one of a predefined list of relationship types.
- Refer to the Assetic Knowledge Base article Asset To Asset Association for associating assets via the Assetic REST API's
- Service Criteria - Each component may have 0,1 or many Service Criteria Types, and for each type there may be 0,1 or many Service Criteria records, representing assessments over a period of time. The most current Service Criteria score for each Service Criteria Type is flagged to make it simpler to get just the current Service Criteria score.
Assets - Core Fields
Central to the Asset API's are the core asset fields which are shown below. In addition the remaining common attribute fields and attribute fields particular to each asset category may be managed via the Asset REST API's.
The core asset fields that are specified fields in the Asset API's are:
| Field | Description |
| Id | Unique system GUID for asset. This is immutable |
| AssetId | User visible asset ID |
| AssetName | Name of the asset. This field is not unique but is mandatory |
| AssetCategory | User visible name for asset category |
| AssetCategoryId | Unique system GUID for category. This is immutable |
| AssetExternalIdentifier | External Reference field. |
| LastModified | Last datetime of modification of asset record |
| AssetClass | Asset Classification field |
| AssetSubClass | Asset Classification field |
| AssetType | Asset Classification field |
| AssetSubType | Asset Classification field |
| AssetCriticality | Asset Classification field |
| AssetWorkGroup | Asset Classification field. The default work group for the asset. |
| WorkGroups | Asset Classification field. A list of work groups for the asset. |
| Status | User friendly value of Asset Status |
| AssetMaintenanceType | Asset Classification field |
| AssetMaintenanceSubType | Asset Classification field |
| AssetSecurityGroup | The Asset Security Group defined for the asset which allows for access to specific Assets to be restricted to groups of users |
| AssetPrimaryServiceAreaName | Asset Classification field |
| AssetSecondaryServiceAreaName | Asset Classification field |
Asset Attribute Fields
In addition to the core asset fields, the Asset API's support all other fields that can be defined for an asset as 'attribute' fields. These fields are formatted as a list in the API payload.
For each asset category there are a set of predefined attribute fields that are specific to the types of asset that the category represents. There are overlaps between categories of these attributes, and in many cases the attributes are common to all categories, such as 'Zone'.
The attribute field names are identified in the Asset API's by the 'internal ' name of the field, and not the user friendly display name presented in the Assetic UI. To obtain the internal field name of the asset attributes refer to the Assetic Knowledge Base article Attribute Fields - Assets and Functional Location.
Components
Components have set of core attribute/definition fields as listed in the table below:
| Field | Description | Data Type | Mandatory on creation |
| Id | Unique internal identifier generated by the system on component creation | GUID | No |
| Name | Corresponds to the Component ID in the UI. System generated unique identifier. | String | No |
| Label | Corresponds to the Component Name in the Assetic UI | String (80) | Yes |
| AssetId | User Friendly Asset Id | String | Yes |
| ComponentType | There is a set list of component types defined per asset category by the system administrator. | String (100) | Yes |
| NetworkMeasureType | Network Measure Type defines how the component dimensions are to be defined, and include "Length","Area","Diameter". There is a set list of Network Measure Types defined at a system level. | String | Yes |
| DimensionUnit | The unit of measure of the network measure. There is a set list of Dimension Unit types defined at a system level. | String | Yes |
| MaterialType | The primary material type of the component. There is a set list of user definable material types defined by the system administrator. | String (100) | No |
| DesignLife | The design life of the component | Int | No |
| ExternalIdentifier | An external identifier (external reference number) | String (200) | No |
| LastModified | Last modified date of the component | Datetime | No |
| FinancialClassName | The financial class of the component. | String | No |
| FinancialClassSubName | The financial subclass of the component. | String | No |
Dimensions (Network Measure)
A dimension is added to a component, and is a measurement/quantity value.
More than one dimension record may be applied to a component.
A dimension may have a shape definition
Dimension records are defined by the fields listed in the table below:
| Field | Description | Data Type | Mandatory on creation |
| Id | Unique internal identifier generated by the system on component creation | GUID | No |
| ComponentId | The unique ID of the component that the dimension is applied to. | GUID | Yes |
| RecordType | One of "Addition" (positive measure),"Subtraction" (negative measure) or "Info" (not used to determine overall measure) | String | Yes |
| NetworkMeasure | The dimension value to apply (greater than zero) | Float | Yes |
| Multiplier | A multiplier to apply to the dimension. Default is 1 if omitted. | Float | Optional |
| Unit | The unit of measure. Unit options visible in Assetic UI. Unit must be consistent with NetworkMeasureType. | String | Yes |
| NetworkMeasureType | The type of measure, such as "Length" or "Area". (See list below) | String | Yes |
| Comments | A free text comment | String | No |
| ShapeName | The type of shape used to define the dimension | String | No |
| ShapeLabel | User friendly description of the type of shape used to define the dimension | String | No |
| Diameter | Diameter measure | Float | No |
| DiameterUnit | Unit of measure | String | No |
| Length | Length measure | Float | No |
| LengthUnit | Unit of measure | String | No |
| Width | Width measure | Float | No |
| WidthUnit | Unit of measure | String | No |
| Depth | Depth measure | Float | No |
| DepthUnit | Unit of measure | String | No |
| Height | Height measure | Float | No |
| HeightUnit | Unit of measure | String | No |
| Base | Base measure | Float | No |
| BaseUnit | Unit of measure | String | No |
| Top | Top measure | Float | No |
| TopUnit | Unit of measure | String | No |
Network Measure Type
Network measure types are listed in the Assetic UI. The current list of Network Measure Types is:
Quantity, Area, Height, Length, Volume, Width, Weight, and NotDefined
Functional Location
Functional location has a similar structure to assets in that there are core fields, plus additional attribute fields.
Core Functional Location Fields
| Field | Description | Data Type | Mandatory on creation |
| Id | Unique internal identifier generated by the system on functional location creation | GUID | No |
| FunctionalLocationId | The unique user friendly ID of the functional location. | String | Not Required if auto-id generation on for the location type. |
| FunctionalLocationName | Descriptive name for the functional location | String | Yes |
| FunctionalLocationTypeId | Unique internal identifier for the Functional Location Type. | GUID | Yes |
| FunctionalLocationType | Descriptive name for the functional Location Type | String | No |
| ExternalIdentifier | External Reference field | String | No |
Functional Location Attribute Fields
In addition to the core Functional Location fields, the Functional Location API's support all other fields that can be defined for a Functional Location as 'attribute' fields. These fields are formatted as a list in the API payload.
For each Functional Location Type there are a set of predefined attribute fields that are specific to the type of Functional Location. There are overlaps between Functional Location Types, and in many cases the attributes are common to all categories, such as 'Zone' (internal name is 'GroupAssetZone').
The attribute field names are identified in the Functional Location API's by the 'internal ' name of the field, and not the user friendly display name presented in the Assetic UI. To obtain the internal field name of the Functional Location attributes refer to the Assetic Knowledge Base article Attribute Fields - Assets and Functional Location.
Asset to Functional Location Linking
An asset can be linked to a single functional location. The asset and the Functional Location need to both exist prior to linking. The asset may also be disassociated from a Functional Location, or associated with a different Functional Location.
Service Criteria
The Service Criteria fields are listed in the table below
| Field | Description | Data Type |
| Id | Unique internal identifier generated by the system | Integer |
| AssessmentDate | The date entered by the user defining the date the assessment took place | Date |
| Score | The Service Criteria score. An integer ranging from 0 to 6 | Integer |
| CreatedDate | The timestamp of when the record was created in Assetic | Datetime |
| IsMostRecentScore | Boolean indicating record is the most recent score for the given component and Service Criteria Type | Boolean |
| AssetCategory | The Asset Category of the asset that the assessment relates to. This is the user friendly name of the category as presented to the user in the Assetic UI | String |
| AssetCategoryId | The internal Assetic GUID identifier for the the Asset Category | GUID |
| AssetId | User friendly asset id of the asset that the assessment relates to | String |
| ComponentId | User friendly Component Id of the component that the assessment relates to | String |
| AssessedByResourceId | The Assetic internal GUID of the resource that performed the assessment. | GUID |
| AssessedByResourceName | The user friendly name of the resource that performed the assessment. | String |
| ServiceCriteriaTypeId | The Assetic internal GUID of the Assessment Type that the assessment relates to. | GUID |
| ServiceCriteriaTypeLabel | The user friendly name of the Assessment Type | String |
| ServiceCriteriaTypeGroup | The user friendly name of the Assessment Type grouping that the assessment relates to | String |
NOTE There are no API's available for creating a Service Criteria Score. Instead use the Data Exchange module to bulk import Service Criteria. There is an API for Data Exchange to allow automation of this process.
